Node mesh object methods

Most used:

• mesh:numNodes()
• mesh:nodeCoordAccessor()
• mesh:nodeValueAccessor()

Index:

• Mesh metadata methods
  • mesh:id()
  • mesh:hasCapability()
• Node geometry methods
  • mesh:numNodes()
  • mesh:numGhostNodes()
  • mesh:totalNumNodes()
  • mesh:nodeCoordInfo()
  • mesh:nodeCoordAccessor()
  • mesh:addNodes()
  • mesh:addGhostNodes()
• Node data methods
  • mesh:nodeAttributeIds()
  • mesh:nodeStateVarIds()
  • mesh:nodeValueInfo()
  • mesh:nodeValueAccessor()
  • mesh:addNodeValueSet()
  • mesh:removeNodeValueSet()
  • mesh:clearNodeValueSets()
• Ghost nodes index conversion methods
  • mesh:toLinearGhostIndex()
  • mesh:toLocalGhostIndex()
• History methods
  • mesh:saveState()
  • mesh:saveNodeValueState()
  • mesh:numNodeValueStates()
  • mesh:nodeValueStateTag()
  • mesh:nodeValueStateTime()
  • mesh:setNodeValueStateTag()
  • mesh:setNodeValueStateTime()
• Other methods
  • mesh:nodeSets()
  • mesh:clear()
  • mesh:emitMeshChanged()
  • mesh:print()
  • mesh:printValues()

Mesh metadata methods

mesh:id()
Description:	Returns the mesh name.
Parameters:	None.
Returns:	Returns a string with the mesh name (the id attribute given during its model definition).

Example:

local m = modelData:mesh('myMeshName')

local meshId = m:id()
assert(meshId == 'myMeshName')

mesh:hasCapability(capName)
Description:	Check mesh capabilities. Capabilities are functionalities that are optionally implemented by a mesh plugin. This function allows to check if the mesh implements or not each of the optional functionalities.
Parameters:	capName - The capability name to be queried. Standard capability names are "addNodes", "addCells", "editGroups", "topology", "ghostNodes" and "clear". Other capabilities might be implemented by specific mesh plugins.
Returns:	Returns true if the mesh supports the requested functionality, false if not.

Example:

if not m:hasCapability('addNodes') then
  error('Model requires a mesh with addNodes capability')
end

Node geometry methods

mesh:numNodes()
Description:	Returns the number of geometry nodes in the mesh.
Parameters:	None.
Returns:	Returns the number of nodes in the mesh.

Example:

local nnodes = m:numNodes()

mesh:numGhostNodes()
Description:	Returns the number of ghost nodes in the mesh. Ghost nodes are additional mesh points that are not part of the geometry description, but can be used for calculations (represent degrees of freedom).
Parameters:	None.
Returns:	Returns the number of ghost nodes in the mesh.

Example:

local nghost = m:numGhostNodes() 

mesh:totalNumNodes()
Description:	Returns the total number of nodes in the mesh (geometry + ghost).
Parameters:	None.
Returns:	Returns the total number of nodes in the mesh.

Example:

local ntotal = m:totalNumNodes()
assert(ntotal = m:numNodes() + m:numGhostNodes())

mesh:nodeCoordInfo()
Description:	Returns an object with metadata about mesh coordinates.
Parameters:	None.
Returns:	Returns the coordinate value info object.

Example:

local coordInfo = m:nodeCoordInfo()

mesh:nodeCoordAccessor(unit)
Description:	Returns a value accessor object that can be used to retrieve and update mesh coordinates.
Parameters:	unit - An optional string with the desired unit for returned values. If different from the mesh coordinate unit, the accessor will automatically convert values.
Returns:	A coordinate value accessor object or nil on errors (the requested unit is incompatible with the coordinate unit, for example).

Example:

local coordAc1 = m:nodeCoordAccessor()
local coordAc2 = m:nodeCoordAccessor('cm')  -- An accessor that returns values converted to cm

mesh:addNodes(numNodes)
Description:	Adds the specified number of nodes to the mesh, whithout initializing their coordinates. After calling this function, make sure to initialize node coordinates by using a node accessor. Attribute values and state variables for the new nodes are initialized with their respective default values. IMPORTANT: When redimensioning the mesh, if at all possible, avoid calling this function several times in a sequence. Calling it once with the total number of nodes is much more efficent than calling it repeatedlly with just a few nodes. If nodes are added during the simulation loop, please remember to call mesh:emitMeshCanged(). This function can only be called if mesh:hasCapability("addNodes") returns true.
Parameters:	numNodes - The number of nodes to add to the mesh.
Returns:	Returns the index of the first new included node.

Example:

local pos = m:addNodes(10)  -- Add ten nodes to mesh m.

-- Init coordinates
local ac = m:nodeCoordAccessor()
for i = 1, 10 do
  local coord = {....}  -- Fill table with node coordinates

  ac:setValue(pos, coord)
  pos = pos + 1
end

m:emitMeshChanged()

mesh:addGhostNodes(numNodes)
Description:	Adds the specified number of ghost nodes to the mesh, whithout initializing their coordinates. After calling this function, make sure to initialize node coordinates by using a node accessor. Attribute values and state variables for the new nodes are initialized with their respective default values (if those attributes store values for ghost nodes at all - check the attribute's affectedNodes property). IMPORTANT: When redimensioning the mesh, if at all possible, avoid calling this function several times in a sequence. Calling it once with the total number of nodes is much more efficent than calling it repeatedlly with just a few nodes. If nodes are added during the simulation loop, please remember to call mesh:emitMeshCanged(). This function can only be called if mesh:hasCapability("ghostNodes") returns true.
Parameters:	numNodes - The number of ghost nodes to add to the mesh.
Returns:	Returns the index of the first new included ghost node (a value from 1 to mesh:numGhostNodes(), without the high bit set).

Example:

local pos = m:addGhostNodes(10) -- Add ten ghost nodes to the mesh

-- Init coordinates
local ac = m:nodeCoordAccessor()
for i = 1, 10 do
  local coord = {....}  -- Fill table with node coordinates

  ac:setValue(setMeshGhostFlag(pos), coord)
  pos = pos + 1
end

m:emitMeshChanged()

Node data methods

mesh:nodeAttributeIds()
Description:	Returns a list with the name (id) of every node attribute associated with the mesh.
Parameters:	None.
Returns:	Returns a table with node attribute ids (strings).

Example:

local nodeAttrIds = m:nodeAttributeIds()

mesh:nodeStateVarIds()
Description:	Returns a list with the name (id) of every state variable associated with the mesh.
Parameters:	None.
Returns:	Returns a table with state variable ids (strings)

Example:

local stateVarIds = m:nodeStateVarIds()

mesh:nodeValueInfo(name)
Description:	Returns an object with metadata information about the named mesh node value (either a state variable or a node attribute).
Parameters:	name - The attribute / state variable name (id).
Returns:	Returns a value info object or nil if the requested name was not found in the mesh.

Example:

local uInfo = m:nodeValueInfo('u')

mesh:nodeValueAccessor(name, unit) mesh:nodeValueAccessor(name, state, locked, unit)
Description:	Returns a value accessor object that can be used to retrieve and update node data for attributes or state variables. Can be called with two different signatures. The first, receiving only the attribute / state variable name and an optional unit, always retrieves data from the current state and is the most used. The second, allows for defining the desired state from which data will be recovered / written. As a matter of fact, the first format is equivalent to calling the second one as mesh:nodeValueAccessor(name, 0, true, unit).
Parameters:	name	The name (id) of the state variable or node attribute.
	state	An optional state number referencing the history state that the accessor will operate on. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested variable, which can be queried with a call to mesh:numNodeValueStates(). Remember that for a value accessor to support states, the history parameter must be set on its value info object.
	locked	The locked parameter controls the behaviour of the accessor once a new state is created for the value. The 'lock' refers to the state number, so if locked is false and a new state is created, the accessor doesn't change and continues to point to the same data. If locked is true, the accessor will be locked to that state number, so when a new state is created, the accessor changes the data its looking upon to reflect the new state. For example, an accessor locked on state 0 will always point to the current state, and one locked to state 1 will always point to the previous saved value.
	unit	An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns:	A value accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local uAc  = m:nodeValueAccessor('u')          -- Returns an accessor to the 'u' state variable
local uAc2 = m:nodeValueAccessor('u', 'cm')    -- Returns an accessor to the 'u' state variable with values converted to cm
local sAc  = m:nodeValueAccessor('S', 1, true) -- Returns an accessor locked on the previous saved value of attribute 'S'

mesh:addNodeValueSet(valInfo)
Description:	Creates a new value set for storing data for a new node attribute and associates this new attribute with the mesh.
Parameters:	valInfo - A new value info object created by a call to ValueInfo(), with valueKind equal to "node attribute" or "node state variable".
Returns:	Returns true on success, false on error.

Example:

local newInfo = ValueInfo('node attribute', {id = 'new1', unit = 's'})
assert(m:addNodeValueSet(newInfo) == true)

mesh:removeNodeValueSet(name)
Description:	Removes the named attribute or state variable from the mesh. Use carefully.
Parameters:	name - The name (id) of the state variable or node attribute.
Returns:	Nothing.

Example:

m:removeNodeValueSet('S')

mesh:clearNodeValueSets()
Description:	Removes all node attributes and state variables from the mesh. Use carefully.
Parameters:	None.
Returns:	Nothing.

Example:

m:clearNodeValueSets()

Ghost nodes index conversion methods

mesh:toLinearGhostIndex(index)
Description:	Converts a ghost index into a linear index. Not very needed since accessor objects can be indexed by either ghost indices or linear indices.
Parameters:	index - A value between 1 and mesh:numGhostNodes(), with the high bit set.
Returns:	Returns the equivalent linear index (a value between 1 and mesh:totalNumNodes()). If a common, geometry node index, is received instead of a ghost index, returns the received value.

Example:

local linearIndex = m:toLinearGhostIndex(ghostIndex)

mesh:toLocalGhostIndex(index)
Description:	Converts a linear ghost index into an index suitable for indexing a "ghost" only accessor (a value between 1 and mesh:numGhostNodes(), with the high bit cleared). This function is rarely needed. Using the accessor:adjustLinearIndex() method is usually more convenient.
Parameters:	index - A ghost node linear index (a value between mesh:numNodes() + 1 and mesh:totalNumNodes()).
Returns:	Returns the equivalent "local" index or nil if index references a geometry node instead of a ghost node.

Example:

local localIndex = m:toLocalGhostIndex(linearIndex)

History methods

mesh:saveState(mode)
Description:	Saves the current state for all node values that support state saving (values defining a history mode), creating a new current state. The time associated with the new current state is initialized to the value of the current simulation time (set either explicitly by a call to setCurrentTime() or implicitly by some process functions).
Parameters:	mode - The requested save mode, defining how the new state will be initialized. Can be one of the following strings: "init" (new state is initialized with the data default value), "noinit" (new state is not initialized at all) or "copy" (new state is initialized with a copy of the current state).
Returns:	Returns true if successful, false otherwise.

Example:

m:saveState('init')

mesh:saveNodeValueState(name, mode)
Description:	Saves the current state for the given node attribute / state variable, creating a new current state. The time associated with the new current state is initialized to the value of the current simulation time (set either explicitly by a call to setCurrentTime() or implicitly by some process functions). This can later be changed by a call to mesh:setNodeValueStateTime().
Parameters:	name	The name (id) of the state variable or node attribute.
	mode	The requested save mode, defining how the new state will be initialized. Can be one of the following strings: "init" (new state is initialized with the data default value), "noinit" (new state is not initialized at all) or "copy" (new state is initialized with a copy of the current state).
Returns:	Returns true if successful, false otherwise. In particular, this function returns false if the given attribute does not have history values enabled.

Example:

m:saveNodeValueState('u', 'noinit')

mesh:numNodeValueStates(name)
Description:	Returns the number of existing history states for the given attribute / state variable.
Parameters:	name - The name (id) of the state variable or node attribute.
Returns:	Returns the number of existing states or -1 for unknown names.

Example:

local nstates = m:numNodeValueStates('u')

mesh:nodeValueStateTag(name, state)
Description:	Returns the tag attached to the requested state, for the given node attribute / state variable.
Parameters:	name	The name (id) of the state variable or node attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested value / state variable, which can be obtained with a call to mesh:numNodeValueStates().
Returns:	The state tag attached to the requested state or "" if the name doesn't exists.

Example:

local tag    = n:nodeValueStateTag('u', 0)  -- Tag from the current state
local oldTag = n:nodeValueStateTag('u', 1)  -- Tag from the previous state

mesh:nodeValueStateTime(name, state)
Description:	Returns the time attached to the requested state, for the given node attribute / state variable.
Parameters:	name	The name (id) of the state variable or node attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested value / state variable, which can be obtained with a call to mesh:numNodeValueStates().
Returns:	The time attached to the requested state or -1 if the name doesn't exists.

Example:

local t    = n:nodeValueStateTime('u', 0)  -- Time from the current state
local oldt = n:nodeValueStateTime('u', 1)  -- Time from the previous state

mesh:setNodeValueStateTag(name, state, tag)
Description:	Updates the tag attached to the requested state, for the given node attribute / state variable.
Parameters:	name	The name (id) of the state variable or node attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested value / state variable, which can be obtained with a call to mesh:numNodeValueStates().
	tag	The new state tag.
Returns:	Nothing.

Example:

m:setNodeValueStateTag('u', 1, 'myTag') -- Updates the tag from the previous state for state variable 'u'

mesh:setNodeValueStateTime(name, state, time)
Description:	Updates the time attached to the requested state, for the given node attribute / state variable.
Parameters:	name	The name (id) of the state variable or node attribute.
	state	The state number, referencing the history state to be queried. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested value / state variable, which can be obtained with a call to mesh:numNodeValueStates().
	time	The new state time, expressed in the same unit as the current simulation time unit.
Returns:	Nothing.

Example:

m:setNodeValueStateTime('u', 1, 12.5) -- Updates the time from the previous state for state variable 'u'

Other methods

mesh:nodeSets()
Description:	Returns a map storing the configured set of node set objects.
Parameters:	None.
Returns:	Returns a table indexed by node set names, with each entry storing a reference to a node set object.

Example:

-- Prints the name and number of nodes for each node set in the mesh
local nodeSets = m:nodeSets()

for name, nset in pairs(nodeSets) do
  print(name, nset:numNodes())
end

mesh:clear()
Description:	Clears the mesh contents, removing nodes, cells and data associated with them. Can only be called if mesh:hasCapability("clear") returns true. Keep in mind that this function does not remove the set of state variables or attributes added to the mesh, although it clears its stored values.
Parameters:	None.
Returns:	Nothing.

Example:

m:clear()

mesh:emitMeshChanged()
Description:	Signal the world that the mesh has changed. Should be called after finishing editions to the mesh, like adding new nodes / cells or changing cell geometry. This signal is captured, for example, by the FEM process to update its internal structures if the mesh changes during the orchestration between simulation steps.
Parameters:	None.
Returns:	Nothing.

Example:

m:emitMeshChanged()

mesh:print()
Description:	Print mesh parameters.
Parameters:	None.
Returns:	Nothing.

Example:

m:print()

mesh:printValues(evalFunctions)
Description:	Print mesh values.
Parameters:	evalFunctions - An optional flag to enable function evaluation while printing values. If true, function values, not names, will be printed if an attribute value is an user function. Default = false.
Returns:	Nothing.

Example:

m:printValues()
m:printValues(true)